AuthorWords 


July 1994, Volume 1, Issue 3 


© 1994 Solis, Incorporated 


Authoring Style & Standards: A Hegemonic Approach 


s with any programming lan- 
guage, you can use Authorware 
to create very complicated pro- 
grams. During initial development, this 
complexity is usually not a problem. 
Later on, however, it can be a stumbling 
block to revisions and enhancements. 
You understood 
what you were doing 


dards - the organization and documenta- 
tion of the icons you line up on the flow 
line. It also suggests some guidelines 
for developing authoring standards. 


Icon Titles 

Examine Figure | and try to figure 
out what these icons do. 
It really isn't possible 


the day you created i from looking at the 
that long string of [a] Untitled flow line. If another 
untitled icons, but person had to modify 
do you remember this logic, he or she 
now that six months [> ais | Untitled would spend a lot of 


have passed? Each 
author develops his 
or her own way, or 
style of organizing 
an Authorware pro- 
gram. While it is 
impossible to make 
everyone conform 
to a single authoring 
style, it is important 
to lay down standards to insure that pro- 
gram organization is readily understood 
and modified by others. This article ex- 
plains the importance of authoring stan- 


C=) Untitled 


Untitled 


MM User Conference 


f you are attending the 
Macromedia International User 
Conference in September, be 
sure to stop by and see us at the Solis 
booth (exhibit 210). We would love to 
receive AuthorWords feedback in 
person. 

Jeff Burton, one of the AuthorWords 
editors, is also scheduled to speak at the 
conference on the topic of connecting 


C ’ Authorware to databases. 


paee 


Figure 1. 


Untitled 


Untied time just trying to fig- 


ure out what was going 
on. The picture only 
shows a few icons. 
Imagine opening a file 
and finding thousands 
of icons, cryptically la- 
belled. In this situa- 
tion, you would proba- 
bly be tempted with 
two courses of action. The first would 
be to simply start from scratch, which 
in some cases might be your best al- 
terative. The second would be to 
track down the person responsible 
and strangle him or her with your 
mouse cord. We strongly discourage 
the second course of action. 

The nature of software projects is 
that they are seldom completely fin- 
ished. There is always something to 
be changed, whether it comes a year af- 
ter it has been in service, or the day after 
the product is delivered (more likely). 
Authoring standards insure against fu- 
ture change. They enforce rules that re- 
sult in structure and documentation built 
into the program's source code that make 


Untitled 
Untitled 
Untitled 


it easier for you or someone else to fix 
bugs, and add or revise features. Some- 
times standards might seem a distracting 
nuisance that impede creativity. They 
are. In the "heat of the battle," it is easy 
to throw icons into the file while ideas 
are fresh and tangible, and there is noth- 
ing wrong with that. Discipline is re- 
quired, however, to go back and orga- 
nize, codify, and document what you 
have done. The little bit of extra effort 
it takes to apply the standards will reap 
big savings in time later on. 

The underlying fundamental of a 
good authoring style is that the program 
should be understandable simply by 
reading the icon titles on the flow line. 

This maxim should guide the devel- 
opment of all authoring standards. No 
icon should remain without a title. Ti- 
tles should be short, but descriptive and 
meaningful. Figure 2 shows a sort of ex- 
istential titling style that should be 
avoided. Cryptic titles are as bad as no 
labels at all. 


Level 1 


Loop some 


Lotsa icons in here 
More stuff here (if we get this far) 
Icons waiting to happen 


Figure 2. 


In general icon titles should either 
describe What the icon is or what the 
icon does. For example, a display icon 
is a noun; it is something. On the other 
hand, a decision or calculation icon is a 
verb; it does something. The gauge of 
quality for icon titles is whether the title 

(Continued on page 2) 
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(Continued from page 1) 
requires the author to open the icon to 


see what it is. If the title heads off a 
double-click, then it has succeeded. Fig- 
ure 3 shows some acceptable icon titles. 


Revolution 


Factory Diagram 


Proletariat 
Move Proletariat out of factory 


Initiate Strike 


Decide what happens 


Bourgeoisie crushes stiike; wage slaves resume work 
Strike succeeds, initiate dictatorship of proletariat 


Figure 3. 


Sometimes it is helpful to include 
program data in an icon title. This tech- 
nique allows authors to make changes to 
the way the program works by simply 


Preview of New CMI from 


t is only fair to warn our good 
readers that this article is going 
to shamelessly promote a 
product in which the editorial staff has a 
material interest. The following shares 
much in common with the diet pill 
advertisements in the newspaper that try 
to disguise themselves as legitimate 
news items. You have been warned. 

Authorware is great for creating tots 
of wonderful interactive training, and 
even at tracking what the learner does 
while taking training. But what about 
the bigger picture? Where does all that 
information go? How do learners get 
inside the Authorware lessons? Solis 
has developed an answer to those 
questions. It is called Pathway. 

Pathway is a complete Computer 
Managed Instruction system for 
Windows. It provides a way to organize 
discrete lessons into a _ coherent 
curriculum and deliver them in an 
orderly fashion. It tracks learners, 
courses, and enrollments and provides a 
way to manage all of them with the click 
of a mouse. 

Pathway starts with a curriculum 


es and Standards 


changing an icon title, rather than having 
to open up the icon. Basically this 
works by manipulating the system vari- 
able IconTitle. Figure 4 shows an exam- 
ple. Notice that the calculation sets the 
user variable path 
to the first number 
in the icon title. In 
this case, the num- 
ber is five. The 
author can change 
the number in the 
icon title and thus 
influence the flow 
of the program 
without opening 
the calculation. 


Naming Variables 

The first rule of naming variables is: 
make the names meaningful. The name 
must provide a clue to what it does. Ex- 


Solis 


designer called Pathmaker. Pathmaker 
is an easy-to-use outliner that pulls 
together learning resources into a course 
file. It allows the curriculum designer to 
establish relationships between learning 
resources such as prerequisites and 
weighted scores. Pathway uses the 
resulting course description file to 
present the course to learners and route 
them-through the curriculum. 

Pathway delivers and manages 
courses through a_ simple, iconic 
interface. Pathway communicates with 
computer-based learning activities 
through text files and works with other 
authoring systems besides Authorware. 

One of Pathway’s advantages is its 
flexibility. Learner data is stored in a 
database. Pathway is not tied to one 
particular database. As an ODBC-aware 
(Open Database Connectivity) 
application, it can store its information 
in many different kinds of database, 
from Oracle down to Access. 

This space is too small to detail all of 
Pathway’s features. If you are interested 
in finding out more about Pathway, call 
Solis at (415) 696-8700. 


ercise: try to determine what the follow- 
ing variables do: 


a, str, ZZZ, var 
You don't know what they do because 


they are ineptly named. Variable names 
(Continued on page 3) 


A Word from the Editors 


itting as high as we do on the 
food chain, we human beings 
can sometimes relax and 
contemplate some of life’s simpler 
pleasures, such as Authorwords, and the 
comfort it provides. We at Authorwords 
enjoy comfort too, but this issue forced 
us into the uncomfortable position of 
reneging on our promise of cross- 
platform and DLL covereage. 

Because our clients always come 
first, we had to make some adjustments 
in this edition. Look for the cross- 
platform discussion in a future 
Authorwords. We apologize if you were 
waiting for this issue before starting that 
20,000 icon Windows port. 


Herr Doktor Ikon Answers 
Your Authoring Questions 


oktor Ikon’s controversial new 
treatment for hysteria (continue 
branching for all responses) has 
kept him-busy over the lasi- few months. 
He has taken a short break, however, to 
respond to a question about the appro- 
priateness of the EraseIcon() function: 

“The origin of the EraseIcon() taboo, 
deeply ingrained in our collective au- 
thoring psyche, lies far in the past. I, 
like many modern icon therapists, have 
advocated its use. But only sparingly! 
Indiscriminate application of EraseIcon 
is confusing and dangerous (IconID 
links are as fragile as an underdeveloped 
ego). An example of judicious use of 
EraseIcon() is in a model which must 
erase a display external to itself.” 


Warning: Do not take internally. If 
swallowed, do not induce vomiting. Doktor 
ikon is not a real doctor. 


| 
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(Continued from page 2) 
should describe what they contain. Ab- 
breviations and acronyms are alright, as 


Bird 
Cat 
Dog 
Cow 
Slow Laurus 


-- Get the path number 
Path := GetNumber{1_ IconTitle) 


Figure 4. 


long as they are obvious. It is also ok to 
have a few throw-away or catchall vari- 
ables to contain temporary, transient in- 
formation. Be very careful in using this 
kind of variable, however. Make certain 
that the information is really only 
needed locally and temporarily. 

The second rule of naming variables 
is: always include a description of the 
variable. Sometimes the variable name 
can't completely describe the intricacies 
of the variable's characteristics. The de- 
scription can. For example, suppose you 
have a program with a variable called 
Temperature. Six months after you have 
created the file, you open it up. But now 
you can't remember whether the temper- 
ature was in Fahrenheit or Celsius. Hah! 


New Variable 
Name: |Field Des But Status 


Initial value: i tt—“sSCSCOY 


Description: 


Contains the status of the Field 
Destabilizer Button during the first 
scenario of the control panel 
simulation. 

O0=Negative 

1=Neutral 
2=Positive 


Figure 5. 


You can probably determine the units 
from the context, but that would take 
many precious minutes (and you aren't 
being paid by the hour). You should 


have indicated that information in the 

variable description. Look at figure 5. It 

shows a properly documented variable. 
Notice that the description lists 
all the possible values for the 
variable. The wise author who 
created this variable will have 
no trouble determining its func- 
tion. 
A large Authorware file can 


pee §=COntain many variables. It is 


pene not uncommon to see files with 
4 over 100 variables. No one can 
remember the correct spellings 
of 100 variables. This necessi- 
tates many trips to the Show 
Variables dialog box. Scrolling 
through 100 variable names in 
the dialog is tiresome and inef- 
ficient. Categorizing the variables 
makes them much easier to find. Estab- 
lish categories and then use the first one, 
two, or three letters from the category as 
a prefix for each variable in the category. 
For instance, if you had a video cate- 
gory, you could use the V prefix for all 
video-related wg 
variables: 


V Current Frame 
V Last Frame 
V First Frame 


The Show Vari- 
ables dialog al- 
phabetizes the variables, so variables 
with the same prefix will be grouped to- 
gether. 


Calculations 

Calculation icons are disasters wait- 
ing to happen. The Author's mind is full 
of deceit and trickery, and the calcula- 
tion icon gives full reign to those traits. 
Because calculation icons are the most 
error-prone part of an Authorware pro- 
gram, it is extremely important to docu- 
ment them well. You have seen exam- 
ples of badly named icons and badly 
named variables, but they have been 
harmless compared to a mangled calcu- 
lation icon. Gaze, if you can stand it, on 
the monstrosity in figure 6. When con- 
fronted with a calculation like this, go di- 


rectly to your medicine cabinet and pull 
out the biggest bottle of pain-killer you 
have and set it on top of your monitor. 
For those of you who create icons like 
this to impress you boss, we feel a sense 
of shame, but mostly pity. 

Actually, convoluted calculations 
make your life harder both at mainte- 
nance time and during initial authoring. 
If you apply the rules, you will find that 
calculations are easier to create and de- 
bug from the beginning. The first step 
toward better calculations is one we 
have already covered: choose appropri- 
ate names for variables. Which of the 
expressions in figure 7 is easier to deci- 
pher? Notice that the first expression 
didn't really need a comment. The 
names of the variables carried enough 
information for you to instantly grasp 
what was happening. 

The most important thing you can do 
to make calculation icons easier to use is 
to comment heavily, even excessively. 
Every line in the calculation should have 

(Continued on page 4) 


Work with Strings 


string 2 := SubStr{GetLine([string 1. RepCount, RepCount + 4, Tab). CharCount(G: 
string 3 := SubStr{string 2, 4, 8) ~ SubStr(string 2, 1. 3) ~ Return ~ SubSti{string : 
string 4 := ReplaceLine(string 1, ChoiceNumber - 1. GetLine{string 3. GetNumber| 


string 5 -= DeleteLine(string 1. RepCount. RepCount + 1. SubSti{string 1. 3. 3)) 


Figure 6. 


About Solis... 


olis is a professional services 
firm, ready to help you with 
your custom development chal- 
lenges. We have extensive experience 
developing multi-media and computer- 
based training applications for Macin- 
toshes and Windows. Our skills include 
traditional languages such as Pascal and 
C++ as well as Authorware Professional. 
We also train in the use of Authorware. 


Address: 107 South B Street 
Suite 350 
San Mateo, CA 94401 
Phone: (415) 696-8700 


Founders: Jeff Burton 
» Robert Milton 
Tom King 


Authoring Style and Standards 


(Continued from page 3) 
a comment. The comment should 
briefly explain what is happening on the 
next line. If you comment rigorously, 
you can speed development of compli- 
cated calculations. They help you to 
clarify your thinking and make sure that 
the calculation is doing everything nec- 
essary to process the information. Fig- 
ure 8 shows an example. Notice that 
there are blank lines between each 
comment-expression pair. Blank lines 
improve readability in calculations. 
Another technique that makes calcu- 


}- First calculation 
Fahrenheit := 9 * Celsius / 5 + 32 


-- Second calculation 


Temperaturel := 9 * Temperature2 / 5 + 32 


Figure 7. 


lations easier to work with is breaking 
down expressions into simpler state- 
ments. The following expression is cor- 
rect, but difficult to understand: 


Contrast it with the following: 


Process Address 


-- Eliminate any blank lines in the response 
EntryT ext :-= Reduce(Return, EntryT ext) 


-- Read the data file 
File Data := ReadExtFile( FileLocation 
A "data" ) 


-- get line 2 of the data file 
Line 2 := GetLine(File Data, 2) 


-- get field 3 of line 2 
Field := GetLine(Line 2, 3, 3 Tab) 


The intermediate steps provide 
checkpoints at which you can ver- 
ify that things are happening as you ex- 


Documenting Dialogs 

Authorware has many nooks and 
crannies into which you can stuff data, 
variables, calculations, and used chew- 
ing gum. It is just as important to docu- 
ment these slots as it is 
to document calcula- 
tion icons. Always add 
a comment after an ex- 


-- Extract the first line of the address from the response 
Address Line 1 := GetLine{EntryT ext. 1) 


-- Remove any quote characters from the address line 
Address Line 1 := Strip(“\"". Address Line 1) 


Figure 8. 


the comment, but you can scroll them 
horizontally by using the arrow keys or 
mouse. There is a simple trick to work- 


~ ing with Tong expressions in dialog ~ 


boxes. Simply copy the expression out 


_of the dialog box and paste it into a cal- 
‘culation icon. When you are done with 


it, copy it back to the dialog box. 


Did Student Pass? 


[ Repeat 


© [| Times 


pression in a dialog box 
that isn't immediately 
obvious. Figure 9 
shows an example. 


© Random w/o Replacement 
© Random with Replacement 
Q Calculated Path 


ars 


© Until All Selected 
© Until Click 7 Keypress 
© Until TRUE 


70 -- Continue until passed 


C) Reset Paths on Entry © Don't Repeat 


Time Limit: ‘=a Seconds 


CJ Show Time Hemaining 


Unfortunately these 
slots are almost always 
too small to show the 
entire expression and 


-- Get field 3 of line 2 from the file 
Field := GetLine( GetLine ( ReadExtFile( File- 
Location “ “data" ), 2 ), 3, 3, Tab ) 


Figure 9. 
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